<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Processes</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="System-inquiry.xhtml" title="System inquiry"/>
    <link rel="next" href="Time-related-functions.xhtml" title="Time-related functions"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Processes" epub:type="subchapter" id="Processes">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Processes</h2>
          </div>
        </div>
      </div>
      <p>A <em class="firstterm">process</em> is a native (operating-system-level) application or
program that runs separately from the current virtual machine.
</p>
      <p>Many programming languages have facilities to allow access to system
processes (commands).  (For example Java has <code class="literal">java.lang.Process</code>
and <code class="literal">java.lang.ProcessBuilder</code>.)
These facilities let you send data to the standard input, extract the
resulting output, look at the return code, and sometimes even pipe
commands together.   However, this is rarely as easy as it is using
the old Bourne shell; for example command substitution is awkward.
Kawa’s solution is based on these two ideas:
</p>
      <div class="itemizedlist" epub:type="list">
        <ul class="itemizedlist" style="list-style-type: disc; ">
          <li class="listitem" epub:type="list-item">
            <p>A “process expression” (typically a function call) evaluates to a
<code class="literal">LProcess</code> value, which provides access to a Unix-style
(or Windows) process.
</p>
          </li>
          <li class="listitem" epub:type="list-item">
            <p>In a context requiring a string (or a bytevector), an <code class="literal">LProcess</code> is
automatically converted to a string (or bytevector)
comprising the standard output from the process.
</p>
          </li>
        </ul>
      </div>
      <section class="sect2" title="Creating a process" epub:type="division" id="idm139667869542768">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Creating a process</h3>
            </div>
          </div>
        </div>
        <p>The most flexible way to start a process is with either the
<code class="literal">run-process</code> procedure or
the <code class="literal">&amp;`{<em class="replaceable"><code>command</code></em>}</code> syntax
for <a class="link" href="Processes.xhtml#process-literals">process literals</a>.
</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667869539200" class="indexterm"/> <code class="function">run-process</code> <em class="replaceable"><code><a class="link" href="Processes.xhtml#meta-process-keyword-argument"><em class="replaceable"><code>process-keyword-argument</code></em></a></code></em><em class="replaceable"><code><sup>*</sup></code></em> <em class="replaceable"><code><em class="replaceable"><code>command</code></em></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Creates a process object, specifically a <code class="literal">gnu.kawa.functions.LProcess</code>
object.
A <em class="replaceable"><code>process-keyword-argument</code></em> can be used to set various options,
as discussed below.
</p>
            <p>The <em class="replaceable"><code>command</code></em> is the process command-line (name and arguments).
It can be an array of strings, in which case those are used as the
command arguments directly:
</p>
            <pre class="screen">(run-process ["ls" "-l"])
</pre>
            <p>The <em class="replaceable"><code>command</code></em> can also be a single string, which is split (tokenized)
into command arguments separated by whitespace.
Quotation groups words together just like traditional shells:
</p>
            <pre class="screen">(run-process "cmd a\"b 'c\"d k'l m\"n'o")
   ⇒ (run-process ["cmd"   "ab 'cd"   "k'l m\"no"])
</pre>
            <p>The syntax shorthand <code class="literal">&amp;`{<em class="replaceable"><code>command</code></em>}</code>
or <code class="literal">&amp;sh{<em class="replaceable"><code>command</code></em>}</code> (discussed below)
is usually more convenient.
</p>
          </blockquote>
        </div>
        <div class="literallayout">
          <p><a id="idm139667869528480" class="indexterm"/><span id="meta-process-keyword-argument"/><em class="replaceable"><code>process-keyword-argument</code></em> <code class="literal">::=</code><br/>
    <a class="link" href="Processes.xhtml#meta-process-redirect-argument"><em class="replaceable"><code>process-redirect-argument</code></em></a><br/>
  | <a class="link" href="Processes.xhtml#meta-process-environment-argument"><em class="replaceable"><code>process-environment-argument</code></em></a><br/>
  | <a class="link" href="Processes.xhtml#meta-process-misc-argument"><em class="replaceable"><code>process-misc-argument</code></em></a><br/>
</p>
        </div>
        <p>We discuss <a class="link" href="Processes.xhtml#meta-process-redirect-argument"><em class="replaceable"><code>process-redirect-argument</code></em></a> and
<a class="link" href="Processes.xhtml#meta-process-environment-argument"><em class="replaceable"><code>process-environment-argument</code></em></a> later.
<span id="meta-process-misc-argument"/>The <em class="replaceable"><code>process-misc-argument</code></em> options are just the following:
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal"><span class="bold"><strong>shell:</strong></span></code> <em class="replaceable"><code>shell</code></em>
</dt>
            <dd>
              <p>Currently, <em class="replaceable"><code>shell</code></em> must be one of <code class="literal">#f</code> (which is ignored)
or <code class="literal">#t</code>.  The latter means to use an external shell to tokenize
the <em class="replaceable"><code>command</code></em>.
I.e. the following are equivalent:
</p>
              <pre class="screen">(run-process shell: #t "<em class="replaceable"><code>command</code></em>")
(run-process ["/bin/sh" "-c" "<em class="replaceable"><code>command</code></em>"])
</pre>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>directory:</strong></span></code> <em class="replaceable"><code>dir</code></em>
</dt>
            <dd>
              <p>Change the working directory of the new process to <em class="replaceable"><code>dir</code></em>.
</p>
            </dd>
          </dl>
        </div>
        <span id="process-literals"/>
      </section>
      <section class="sect2" title="Process literals" epub:type="division" id="idm139667869512640">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Process literals</h3>
            </div>
          </div>
        </div>
        <p>A simple <em class="firstterm">process literal</em> is a kind of
<a class="link" href="Named-quasi-literals.xhtml" title="Named quasi-literals">named literal</a> that uses the backtick character
(<code class="literal">`</code>) as the <a class="link" href="Named-quasi-literals.xhtml#meta-cname"><em class="replaceable"><code>cname</code></em></a>.
For example:
</p>
        <pre class="screen">&amp;`{date --utc}
</pre>
        <p>This is equivalent to:
</p>
        <pre class="screen">(run-process "date --utc")
</pre>
        <p>In general the following are
roughly equivalent (using <a class="link" href="String-literals.xhtml#string-quasi-literals">string quasi-literals</a>):
</p>
        <pre class="screen">&amp;`[<em class="replaceable"><code>args</code></em>...]{<em class="replaceable"><code>command</code></em>}
(run-process <em class="replaceable"><code>args</code></em>... &amp;{<em class="replaceable"><code>command</code></em>})
</pre>
        <p>The reason for the “roughly” is if <em class="replaceable"><code>command</code></em> contains
escaped sub-expressions; in that case <code class="literal">&amp;`</code> may process
the resulting values differently from plain string-substitution,
as discussed below.
</p>
        <p>If you use <code class="literal">&amp;sh</code> instead of <code class="literal">&amp;`</code> then a shell is used:
</p>
        <pre class="screen">&amp;sh{rm *.class}
</pre>
        <p>which is equivalent to:
</p>
        <pre class="screen">&amp;`{/bin/sh -c "rm *.class"}
</pre>
        <p>In general, the following are equivalent:
</p>
        <pre class="screen">&amp;sh[<em class="replaceable"><code>args</code></em>...]{<em class="replaceable"><code>command</code></em>}
&amp;`[shell: #t <em class="replaceable"><code>args</code></em>...]{<em class="replaceable"><code>command</code></em>}
</pre>
      </section>
      <section class="sect2" title="Process values and process output" epub:type="division" id="idm139667869498432">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Process values and process output</h3>
            </div>
          </div>
        </div>
        <p>The value returned from a call to <code class="literal">run-process</code> or a process literal
is an instance of <code class="literal">gnu.kawa.functions.LProcess</code>.
This class extends <code class="literal">java.lang.Process</code>, so you can treat it as
any other <code class="literal">Process</code> object.
</p>
        <pre class="screen">#|kawa:1|# (define p1 &amp;`{date --utc})
#|kawa:2|# (p1:toString)
gnu.kawa.functions.LProcess@377dca04
#|kawa:3|# (write p1)
gnu.kawa.functions.LProcess@377dca04
</pre>
        <p>What makes an <code class="literal">LProcess</code> interesting is that it is also
a <a class="link" href="Reading-and-writing-whole-files.xhtml#Blobs">blob</a>, which is automatically
converted to a string (or bytevector) in a context that requires it.
The contents of the blob comes from the standard output of the process.
The blob is evaluated <a class="link" href="Lazy-evaluation.xhtml" title="Lazy evaluation">lazily</a>,
so data it is only collected when requested.
</p>
        <pre class="screen">#|kawa:4|# (define s1 ::string p1)
#|kawa:5|# (write s1)
"Wed Jan  1 01:18:21 UTC 2014\n"
#|kawa:6|# (define b1 ::bytevector p1)
(write b1)
#u8(87 101 100 32 74 97 110 ... 52 10)
</pre>
        <p>The <code class="literal">display</code> procedure prints it in “human” form, as a string:
</p>
        <pre class="screen">#|kawa:7|# (display p1)
Wed Jan  1 01:18:21 UTC 2014
</pre>
        <p>This is also the default REPL formatting:
</p>
        <pre class="screen">#|kawa:8|# &amp;`{date --utc}
Wed Jan  1 01:18:22 UTC 2014
</pre>
        <p>When you type a command to a shell, its output goes to the console,
Similarly, in a REPL the output from the process
is copied to the console output - which can sometimes by optimized
by letting the process inherit its standard output from the Kawa process.
</p>
      </section>
      <section class="sect2" title="Substitution and tokenization" epub:type="division" id="idm139667869488528">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Substitution and tokenization</h3>
            </div>
          </div>
        </div>
        <p>To substitute the variable or the result of an expression
in the command line use the usual syntax for quasi literals:
</p>
        <pre class="screen">(define filename (make-temporary-file))
&amp;sh{run-experiment &gt;&amp;[filename]}
</pre>
        <p>Since a process is convertible a string, we need no special
syntax for command substitution:
</p>
        <pre class="screen">`{echo The directory is: &amp;[&amp;`{pwd}]}
</pre>
        <p>or equivalently:
</p>
        <pre class="screen">`{echo The directory is: &amp;`{pwd}}
</pre>
        <span id="substitution-tokenization"/>
        <p>Things get more interesting when considering the interaction between
substitution and tokenization. This is not simple string
interpolation. For example, if an interpolated value contains a quote
character, we want to treat it as a literal quote, rather than a token
delimiter. This matches the behavior of traditional shells. There are
multiple cases, depending on whether the interpolation result is a
string or a vector/list, and depending on whether the interpolation is
inside quotes.
</p>
        <div class="itemizedlist" epub:type="list">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem" epub:type="list-item">
              <p>If the value is a string, and we’re not inside quotes, then all
non-whitespace characters (including quotes) are literal, but
whitespace still separates tokens:
</p>
              <pre class="screen">(define v1 "a b'c ")
&amp;`{cmd x y&amp;[v1]z}   ⇒  (run-process ["cmd" "x" "ya" "b'c" "z"])
</pre>
            </li>
            <li class="listitem" epub:type="list-item">
              <p>If the value is a string, and we are inside single quotes,
all characters (including whitespace) are literal.
</p>
              <pre class="screen">&amp;`{cmd 'x y&amp;[v1]z'}   ⇒  (run-process ["cmd" "x ya b'c z"])
</pre>
              <p>Double quotes work the same except that newline is an argument
separator. This is useful when you have one filename per line, and the
filenames may contain spaces, as in the output from <code class="literal">find</code>:
</p>
              <pre class="screen">&amp;`{ls -l "&amp;`{find . -name '*.pdf'}"}
</pre>
              <p>This solves a problem that is quite painful with traditional shells.
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p>If the value is a vector or list (of strings), and we’re not inside
quotes, then each element of the array becomes its own argument, as-is:
</p>
              <pre class="screen">(define v2 ["a b" "c\"d"])
&amp;`{cmd &amp;[v2]}  ⇒  (run-process ["cmd" "a b" "c\"d"])
</pre>
              <p>However, if the enclosed expression is adjacent to non-space non-quote
characters, those are prepended to the first element, or appended to
the last element, respectively.
</p>
              <pre class="screen">&amp;`{cmd x&amp;[v2]y}   ⇒  (run-process ["cmd" "xa b" "c\"dy"])
&amp;`{cmd x&amp;[[]]y}   ⇒  (run-process ["cmd" "xy"])
</pre>
              <p>This behavior is similar to how shells handle <code class="literal">"$@"</code>
(or <code class="literal">"${name[@]}"</code> for general arrays), though in Kawa you would
leave off the quotes.
</p>
              <p>Note the equivalence:
</p>
              <pre class="screen">&amp;`{&amp;[array]}   ⇒  (run-process array)
</pre>
            </li>
            <li class="listitem" epub:type="list-item">
              <p>If the value is a vector or list (of strings), and we <span class="emphasis"><em>are</em></span>
inside quotes, it is equivalent to interpolating a single string
resulting from concatenating the elements separated by a space:
</p>
              <pre class="screen">&amp;`{cmd "&amp;[v2]"}
 ⇒  (run-process ["cmd" "a b c\"d"])
</pre>
              <p>This behavior is similar to how shells handle <code class="literal">"$*"</code> (or
<code class="literal">"${name[*]}"</code> for general arrays).
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p>If the value is the result of a call to <code class="literal">unescaped-data</code> then it
is parsed as if it were literal. For example a quote in the unescaped
data may match a quote in the literal:
</p>
              <pre class="screen">(define vu (unescaped-data "b ' c d '"))
&amp;`{cmd 'a &amp;[vu]z'}   ⇒  (run-process ["cmd" "a b " "c" "d" "z"])
</pre>
            </li>
            <li class="listitem" epub:type="list-item">
              <p>If we’re using a shell to tokenize the command, then we add quotes or
backslashes as needed so that the shell will tokenize as described
above:
</p>
              <pre class="screen">(define authors ["O'Conner" "de Beauvoir"])
&amp;sh{list-books &amp;[authors]}
</pre>
              <p>The command passed to the shell is:
</p>
              <pre class="screen">list-books 'O'\''Conner' 'de Beauvoir
</pre>
              <p>Having quoting be handled by the <code class="literal">$construct$:sh</code>
implementation automatically eliminates common code injection problems.
</p>
            </li>
          </ul>
        </div>
        <p>Smart tokenization only happens when using the quasi-literal forms such
as <code class="literal">&amp;`{command}</code>.
You can of course use string templates with <code class="literal">run-process</code>:
</p>
        <pre class="screen">(run-process &amp;{echo The directory is: &amp;`{pwd}})
</pre>
        <p>However, in that case there is no smart tokenization: The template is
evaluated to a string, and then the resulting string is tokenized,
with no knowledge of where expressions were substituted.
</p>
      </section>
      <section class="sect2" title="Input/output redirection" epub:type="division" id="idm139667869467008">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Input/output redirection</h3>
            </div>
          </div>
        </div>
        <p>You can use various keyword arguments to specify standard input, output,
and error streams. For example to lower-case the text in <code class="literal">in.txt</code>,
writing the result to <code class="literal">out.txt</code>, you can do:
</p>
        <pre class="screen">&amp;`[in-from: "in.txt" out-to: "out.txt"]{tr A-Z a-z}
</pre>
        <p>or:
</p>
        <pre class="screen">(run-process in-from: "in.txt" out-to: "out.txt" "tr A-Z a-z")
</pre>
        <span id="meta-process-redirect-argument"/>
        <p>A <em class="replaceable"><code>process-redirect-argument</code></em> can be one of the following:
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal"><span class="bold"><strong>in:</strong></span></code> <em class="replaceable"><code>value</code></em>
</dt>
            <dd>
              <p>The <em class="replaceable"><code>value</code></em> is evaluated, converted to a string (as if
using <code class="literal">display</code>), and copied to the input file of the process.
The following are equivalent:
</p>
              <pre class="screen">&amp;`[in: "text\n"]{command}
&amp;`[in: &amp;`{echo "text"}]{command}
</pre>
              <p>You can pipe the output from <code class="literal">command1</code> to the input
of <code class="literal">command2</code> as follows:
</p>
              <pre class="screen">&amp;`[in: &amp;`{command1}]{command2}
</pre>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>in-from:</strong></span></code> <em class="replaceable"><code>path</code></em>
</dt>
            <dd>
              <p>The process reads its input from the specified <em class="replaceable"><code>path</code></em>, which
can be any value coercible to a <code class="literal">filepath</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>out-to:</strong></span></code> <em class="replaceable"><code>path</code></em>
</dt>
            <dd>
              <p>The process writes its output to the specified <em class="replaceable"><code>path</code></em>. 
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>err-to:</strong></span></code> <em class="replaceable"><code>path</code></em>
</dt>
            <dd>
              <p>Similarly for the error stream. 
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>out-append-to:</strong></span></code> <em class="replaceable"><code>path</code></em>
</dt>
            <dd/>
            <dt class="term"><code class="literal"><span class="bold"><strong>err-append-to:</strong></span></code> <em class="replaceable"><code>path</code></em>
</dt>
            <dd>
              <p>Similar to <code class="literal">out-to</code> and <code class="literal">err-to</code>, but append to the file
    specified by <em class="replaceable"><code>path</code></em>, instead of replacing it.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>in-from: ’pipe</strong></span></code>
</dt>
            <dd/>
            <dt class="term"><code class="literal"><span class="bold"><strong>out-to: ’pipe</strong></span></code>
</dt>
            <dd/>
            <dt class="term"><code class="literal"><span class="bold"><strong>err-to: ’pipe</strong></span></code>
</dt>
            <dd>
              <p>Does not set up redirection. Instead, the specified stream is available
using the methods <code class="literal">getOutputStream</code>, <code class="literal">getInputStream</code>,
or <code class="literal">getErrorStream</code>, respectively, on the resulting <code class="literal">Process</code> object,
just like Java’s <code class="literal">ProcessBuilder.Redirect.PIPE</code>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>in-from: ’inherit</strong></span></code>
</dt>
            <dd/>
            <dt class="term"><code class="literal"><span class="bold"><strong>out-to: ’inherit</strong></span></code>
</dt>
            <dd/>
            <dt class="term"><code class="literal"><span class="bold"><strong>err-to: ’inherit</strong></span></code>
</dt>
            <dd>
              <p>Inherits the standard input, output, or error stream from the
current JVM process. 
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>out-to:</strong></span></code> <em class="replaceable"><code>port</code></em>
</dt>
            <dd/>
            <dt class="term"><code class="literal"><span class="bold"><strong>err-to:</strong></span></code> <em class="replaceable"><code>port</code></em>
</dt>
            <dd>
              <p>Redirects the standard output or error of the process to
the specified <em class="replaceable"><code>port</code></em>.
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>out-to: ’current</strong></span></code>
</dt>
            <dd/>
            <dt class="term"><code class="literal"><span class="bold"><strong>err-to: ’current</strong></span></code>
</dt>
            <dd>
              <p>Same as <code class="literal">out-to: (current-output-port)</code>,
or <code class="literal">err-to: (current-error-port)</code>, respectively. 
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>in-from:</strong></span></code> <em class="replaceable"><code>port</code></em>
</dt>
            <dd/>
            <dt class="term"><code class="literal"><span class="bold"><strong>in-from: ’current</strong></span></code>
</dt>
            <dd>
              <p>Re-directs standard input to read from the <em class="replaceable"><code>port</code></em>
(or <code class="literal">(current-input-port)</code>). It is unspecified how much is read from
the <em class="replaceable"><code>port</code></em>. (The implementation is to use a thread that reads from the
port, and sends it to the process, so it might read to the end of the port,
even if the process doesn’t read it all.) 
</p>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>err-to: ’out</strong></span></code>
</dt>
            <dd>
              <p>Redirect the standard error of the process to be merged with the
standard output. 
</p>
            </dd>
          </dl>
        </div>
        <p>The default for the error stream (if neither <code class="literal">err-to</code> or
<code class="literal">err-append-to</code> is specified) is equivalent to <code class="literal">err-to: 'current</code>.
</p>
        <p><span class="emphasis"><em>Note:</em></span> Writing to a port is implemented by copying the output or error
stream of the process. This is done in a thread, which means we don’t have
any guarantees when the copying is finished. (In the future we might
change <code class="literal">process-exit-wait</code> (discussed later) wait for not only the
process to finish, but also for these helper threads to finish.)
</p>
        <p>A <a class="ulink" href="https://en.wikipedia.org/wiki/Here_document" target="_top">here document</a> is
a form a literal string, typically multi-line, and commonly used in
shells for the standard input of a process.  You can use string literals or
<a class="link" href="String-literals.xhtml#string-quasi-literals">string quasi-literals</a> for this.
For example, this passes the string <code class="literal">"line1\nline2\nline3\n"</code> to
the standard input of <code class="literal">command</code>:
</p>
        <pre class="screen">(run-process [in: &amp;{
    &amp;|line1
    &amp;|line2
    &amp;|line3
    }] "command")
</pre>
        <p>Note the use of <code class="literal">&amp;|</code> to mark the end of ignored indentation.
</p>
      </section>
      <section class="sect2" title="Pipe-lines" epub:type="division" id="idm139667869414528">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Pipe-lines</h3>
            </div>
          </div>
        </div>
        <p>Piping the output of one process as the input of another
is in princple easy - just use the <code class="literal">in:</code>
process argument.  However, writing a multi-stage pipe-line quickly gets ugly:
</p>
        <pre class="screen">&amp;`[in: &amp;`[in: "My text\n"]{tr a-z A-Z}]{wc}
</pre>
        <p>The convenience macro <code class="literal">pipe-process</code> makes this much nicer:
</p>
        <pre class="screen">(pipe-process
  "My text\n"
  &amp;`{tr a-z A-Z}
  &amp;`{wc})
</pre>
        <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667869411040" class="indexterm"/> <code class="function">pipe-process</code> <em class="replaceable"><code>input</code></em> <em class="replaceable"><code>process</code></em><em class="replaceable"><code><sup>*</sup></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>All of the <em class="replaceable"><code>process</code></em> expressions must be <code class="literal">run-process</code> forms,
or equivalent <code class="literal">&amp;`{command}</code> forms.
The result of evaluating <em class="replaceable"><code>input</code></em> becomes the input to the first
<em class="replaceable"><code>process</code></em>; the output from the first <em class="replaceable"><code>process</code></em> becomes
the input to the second <em class="replaceable"><code>process</code></em>, and so on.  The result of
whole <code class="literal">pipe-process</code> expression is that of the last <em class="replaceable"><code>process</code></em>.
</p>
            <p>Copying the output of one process to the input of the next is
optimized: it uses a copying loop in a separate thread. Thus you can
safely pipe long-running processes that produce huge output. This
isn’t quite as efficient as using an operating system pipe, but is
portable and works pretty well.
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Setting the process environment" epub:type="division" id="idm139667869401952">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Setting the process environment</h3>
            </div>
          </div>
        </div>
        <span id="meta-process-environment-argument"/>
        <p>By default the new process inherits the system environment of the current
(JVM) process as returned by <code class="literal">System.getenv()</code>, but you can override it.
A <em class="replaceable"><code>process-environment-argument</code></em> can be one of the following:
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal"><span class="bold"><strong>env-</strong></span></code><em class="replaceable"><code>name</code></em><code class="literal"><span class="bold"><strong>:</strong></span></code> <em class="replaceable"><code>value</code></em>
</dt>
            <dd>
              <p>In the process environment, set the <code class="literal">"<em class="replaceable"><code>name</code></em>"</code> to the
specified <em class="replaceable"><code>value</code></em>. For example:
</p>
              <pre class="screen">&amp;`[env-CLASSPATH: ".:classes"]{java MyClass}
</pre>
            </dd>
            <dt class="term"><em class="replaceable"><code>NAME</code></em><code class="literal"><span class="bold"><strong>:</strong></span></code> <em class="replaceable"><code>value</code></em>
</dt>
            <dd>
              <p>Same as using the <code class="literal">env-<em class="replaceable"><code>NAME</code></em></code> option above, but only if the
<code class="literal"><em class="replaceable"><code>NAME</code></em></code> is uppercase (i.e. if uppercasing <code class="literal"><em class="replaceable"><code>NAME</code></em></code> yields
the same string). For example the previous example could be written:
</p>
              <pre class="screen">&amp;`[CLASSPATH: ".:classes"]{java MyClass}
</pre>
            </dd>
            <dt class="term"><code class="literal"><span class="bold"><strong>environment:</strong></span></code> <em class="replaceable"><code>env</code></em>
</dt>
            <dd>
              <p>The <em class="replaceable"><code>env</code></em> is evaluated and must yield a <code class="literal">HashMap</code>.
This map is used as the system environment of the process. 
</p>
            </dd>
          </dl>
        </div>
      </section>
      <section class="sect2" title="Waiting for process exit" epub:type="division" id="idm139667869386880">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Waiting for process exit</h3>
            </div>
          </div>
        </div>
        <p>When a process finishes, it returns an integer exit code.
The code is traditionally 0 on successful completion,
while a non-zero code indicates some kind of failure or error.
</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667869385216" class="indexterm"/> <code class="function">process-exit-wait</code> <em class="replaceable"><code>process</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>The <em class="replaceable"><code>process</code></em> expression must evaluate to a process
(any <code class="literal">java.lang.Process</code> object).
This procedure waits for the process to finish, and then returns the
exit code as an <code class="literal">int</code>.
</p>
            <pre class="screen">(process-exit-wait (run-process "echo foo")) ⇒ 0
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667869380112" class="indexterm"/> <code class="function">process-exit-ok?</code> <em class="replaceable"><code>process</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Calls <code class="literal">process-exit-wait</code>, and then returns <code class="literal">#false</code>
if the process exited it 0, and returns <code class="literal">#true</code> otherwise.
</p>
            <p>This is useful for emulating the way traditional shell do
logic control flow operations based on the exit code.
For example in <code class="literal">sh</code> you might write:
</p>
            <pre class="screen">if grep Version Makefile &gt;/dev/null
then echo found Version
else echo no Version
fi
</pre>
            <p>The equivalent in Kawa:
</p>
            <pre class="screen">(if (process-exit-ok? &amp;`{grep Version Makefile})
  &amp;`{echo found}
  &amp;`{echo not found})
</pre>
            <p>Strictly speaking these are not quite the same, since the Kawa
version silently throws away the output from <code class="literal">grep</code>
(because no-one has asked for it). To match the output from the <code class="literal">sh</code>,
you can use <code class="literal">out-to: 'inherit</code>:
</p>
            <pre class="screen">(if (process-exit-ok? &amp;`[out-to: 'inherit]{grep Version Makefile})
  &amp;`{echo found}
  &amp;`{echo not found})
</pre>
          </blockquote>
        </div>
        <span id="Exiting-the-current-process"/>
      </section>
      <section class="sect2" title="Exiting the current process" epub:type="division" id="idm139667869370272">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Exiting the current process</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667869369184" class="indexterm"/> <code class="function">exit</code> [<em class="replaceable"><code>code</code></em>]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Exits the Kawa interpreter, and ends the Java session.
Returns the value of <em class="replaceable"><code>code</code></em> to the operating system:
The <em class="replaceable"><code>code</code></em> must be integer, or the special
values <code class="literal">#f</code> (equivalent to -1), or
<code class="literal">#t</code> (equivalent to 0).
If <em class="replaceable"><code>code</code></em> is not specified, zero is returned.
The <em class="replaceable"><code>code</code></em> is a status code; by convention a non-zero
value indicates a non-standard (error) return.
</p>
            <p>Before exiting, finally-handlers (as in <code class="literal">try-finally</code>,
or the <em class="replaceable"><code>after</code></em> procedure of <code class="literal">dynamic-wind</code>) are
executed, but only in the current thread, and only if
the current thread was started normally. (Specifically
if we’re inside an <code class="literal">ExitCalled</code> block with non-zero
nesting - see <code class="literal">gnu.kawa.util.ExitCalled</code>.)
Also, JVM shutdown hooks are executed - which includes
flushing buffers of output ports.  (Specifically
<code class="literal">Writer</code> objects registered with the <code class="literal">WriterManager</code>.)
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667869358896" class="indexterm"/> <code class="function">emergency-exit</code> [<em class="replaceable"><code>code</code></em>]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Exits the Kawa interpreter, and ends the Java session.
Communicates an exit value in the same manner as <code class="literal">exit</code>.
Unlike <code class="literal">exit</code>, neither finally-handlers nor
shutdown hooks are executed.
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Deprecated functions" epub:type="division" id="idm139667869354352">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Deprecated functions</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667869353280" class="indexterm"/> <code class="function">make-process</code> <em class="replaceable"><code>command</code></em> <em class="replaceable"><code>envp</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Creates a <code class="literal">&lt;java.lang.Process&gt;</code> object, using the specified
<em class="replaceable"><code>command</code></em> and <em class="replaceable"><code>envp</code></em>.
The <em class="replaceable"><code>command</code></em> is converted to an array of Java strings
(that is an object that has type <code class="literal">&lt;java.lang.String[]&gt;</code>.
It can be a Scheme vector or list (whose elements should be
Java strings or Scheme strings);  a Java array of Java strings;
or a Scheme string.  In the latter case, the command is converted
using <code class="literal">command-parse</code>.
The <em class="replaceable"><code>envp</code></em> is process environment;  it should be either
a Java array of Java strings, or the special <code class="literal">#!null</code> value.
</p>
            <p>Except for the representation of <em class="replaceable"><code>envp</code></em>, this is similar to:
</p>
            <pre class="screen">(run-process environment: <em class="replaceable"><code>envp</code></em> <em class="replaceable"><code>command</code></em>)
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667869343520" class="indexterm"/> <code class="function">system</code> <em class="replaceable"><code>command</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Runs the specified <em class="replaceable"><code>command</code></em>, and waits for it to finish.
Returns the return code from the command.  The return code is an integer,
where 0 conventionally means successful completion.
The <em class="replaceable"><code>command</code></em> can be any of the types handled by <code class="literal">make-process</code>.
</p>
            <p>Equivalent to:
</p>
            <pre class="screen">(process-exit-wait (make-process <em class="replaceable"><code>command</code></em> #!null))
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Variable"><span class="kind">Variable</span><span class="ignore">: </span><a id="idm139667869337504" class="indexterm"/> <code class="varname">command-parse</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>The value of this variable should be a one-argument procedure.
It is used to convert a command from a Scheme string to a Java
array of the constituent "words".
The default binding, on Unix-like systems, returns a new command to
invoke <code class="literal">"/bin/sh" "-c"</code> concatenated with the command string;
on non-Unix-systems, it is bound to <code class="literal">tokenize-string-to-string-array</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667869333312" class="indexterm"/> <code class="function">tokenize-string-to-string-array</code> <em class="replaceable"><code>command</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Uses a <code class="literal">java.util.StringTokenizer</code> to parse the <em class="replaceable"><code>command</code></em> string
into an array of words.  This splits the <em class="replaceable"><code>command</code></em> using spaces
to delimit words; there is no special processing for quotes or other
special characters.
(This is the same as what <code class="literal">java.lang.Runtime.exec(String)</code> does.)
</p>
          </blockquote>
        </div>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="Processes.xhtml#idm139667869542768">Creating a process</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Processes.xhtml#idm139667869512640">Process literals</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Processes.xhtml#idm139667869498432">Process values and process output</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Processes.xhtml#idm139667869488528">Substitution and tokenization</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Processes.xhtml#idm139667869467008">Input/output redirection</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Processes.xhtml#idm139667869414528">Pipe-lines</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Processes.xhtml#idm139667869401952">Setting the process environment</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Processes.xhtml#idm139667869386880">Waiting for process exit</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Processes.xhtml#idm139667869370272">Exiting the current process</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Processes.xhtml#idm139667869354352">Deprecated functions</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="Miscellaneous.xhtml">Miscellaneous topics</a></p>
        <p>
        Previous: <a accesskey="p" href="System-inquiry.xhtml">System inquiry</a></p>
        <p>
        Next: <a accesskey="n" href="Time-related-functions.xhtml">Time-related functions</a></p>
      </div>
    </footer>
  </body>
</html>
